
<!DOCTYPE html>

<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />

    <title>Administering VLANd support in LAVA &#8212; LAVA 2024.05 documentation</title>
    <link rel="stylesheet" type="text/css" href="_static/pygments.css" />
    <link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css" />
    <script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
    <script src="_static/jquery.js"></script>
    <script src="_static/underscore.js"></script>
    <script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
    <script src="_static/doctools.js"></script>
    <script src="_static/sphinx_highlight.js"></script>
    <link rel="shortcut icon" href="_static/favicon.ico"/>
    <link rel="index" title="Index" href="genindex.html" />
    <link rel="search" title="Search" href="search.html" />
    <link rel="next" title="Administrator debugging" href="pipeline-debug.html" />
    <link rel="prev" title="HTTP proxies" href="proxy.html" />
    <link rel="canonical" href="https://docs.lavasoftware.org/lava/vland-admin.html" />
  
<meta charset='utf-8'>
<meta http-equiv='X-UA-Compatible' content='IE=edge,chrome=1'>
<meta name='viewport' content='width=device-width, initial-scale=1.0, maximum-scale=1'>
<meta name="apple-mobile-web-app-capable" content="yes">
<script type="text/javascript" src="_static/js/jquery-1.12.4.min.js"></script>
<script type="text/javascript" src="_static/js/jquery-fix.js"></script>
<script type="text/javascript" src="_static/bootstrap-3.4.1/js/bootstrap.min.js"></script>
<script type="text/javascript" src="_static/bootstrap-sphinx.js"></script>


  </head><body>

  <div id="navbar" class="navbar navbar-default navbar-fixed-top">
    <div class="container">
      <div class="navbar-header">
        <!-- .btn-navbar is used as the toggle for collapsed navbar content -->
        <button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
          <span class="icon-bar"></span>
        </button>
        <a class="navbar-brand" href="index.html"><span><img src="_static/lava.png"></span>
          LAVA</a>
        <span class="navbar-text navbar-version pull-left"><b>2024.05</b></span>
      </div>

        <div class="collapse navbar-collapse nav-collapse">
          <ul class="nav navbar-nav">
            
                <li><a href="genindex.html">Index</a></li>
                <li><a href="contents.html">Contents</a></li>
            
            
              <li class="dropdown globaltoc-container">
  <a role="button"
     id="dLabelGlobalToc"
     data-toggle="dropdown"
     data-target="#"
     href="index.html">Site <b class="caret"></b></a>
  <ul class="dropdown-menu globaltoc"
      role="menu"
      aria-labelledby="dLabelGlobalToc"><ul class="current">
<li class="toctree-l1"><a class="reference internal" href="index.html">Introduction to LAVA</a></li>
<li class="toctree-l1 current"><a class="reference internal" href="contents.html">Contents</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="glossary.html">Glossary of terms</a></li>
</ul>
<ul>
<li class="toctree-l1"><a class="reference internal" href="support.html">Getting support</a></li>
</ul>
</ul>
</li>
              
                <li class="dropdown">
  <a role="button"
     id="dLabelLocalToc"
     data-toggle="dropdown"
     data-target="#"
     href="#">Page <b class="caret"></b></a>
  <ul class="dropdown-menu localtoc"
      role="menu"
      aria-labelledby="dLabelLocalToc"><ul>
<li><a class="reference internal" href="#">Administering VLANd support in LAVA</a><ul>
<li><a class="reference internal" href="#mandatory-constraints">Mandatory Constraints</a><ul>
<li><a class="reference internal" href="#single-set-of-switches">Single set of switches</a></li>
<li><a class="reference internal" href="#switches-must-have-drivers-in-vland">Switches must have drivers in vland</a></li>
<li><a class="reference internal" href="#accurate-map-of-network-topology">Accurate map of network topology</a></li>
<li><a class="reference internal" href="#identify-primary-interfaces">Identification of primary interfaces</a></li>
<li><a class="reference internal" href="#additional-advice">Additional advice</a></li>
</ul>
</li>
<li><a class="reference internal" href="#example-device-dictionary">Example device dictionary</a><ul>
<li><a class="reference internal" href="#viewing-the-network-map">Viewing the network map</a></li>
</ul>
</li>
</ul>
</li>
</ul>
</ul>
</li>
              
            
            
              
                
  <li>
    <a href="proxy.html" title="Previous Chapter: HTTP proxies"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">&laquo; HTTP proxies</span>
    </a>
  </li>
  <li>
    <a href="pipeline-debug.html" title="Next Chapter: Administrator debugging"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">Administrator... &raquo;</span>
    </a>
  </li>
              
            
            
            
            
              <li class="hidden-sm"></li>
            
          </ul>

          
            
<form class="navbar-form navbar-right" action="search.html" method="get">
 <div class="form-group">
  <input type="text" name="q" class="form-control" placeholder="Search" />
 </div>
  <input type="hidden" name="check_keywords" value="yes" />
  <input type="hidden" name="area" value="default" />
</form>
          
        </div>
    </div>
  </div>

<div class="container">
  <div class="row">
    <div class="body col-md-12 content" role="main">
      
  <section id="administering-vland-support-in-lava">
<span id="admin-vland-lava"></span><span id="index-0"></span><h1>Administering VLANd support in LAVA<a class="headerlink" href="#administering-vland-support-in-lava" title="Permalink to this heading">¶</a></h1>
<section id="mandatory-constraints">
<h2>Mandatory Constraints<a class="headerlink" href="#mandatory-constraints" title="Permalink to this heading">¶</a></h2>
<p>VLANd is a daemon to support virtual local area networks. It can be used alone
and can also be used within LAVA. VLANd is a specialized tool and the LAVA
support cannot and will not protect against misconfiguration causing the
network to become unusable. Admins require careful consideration of the risks
and time to manually prepare a configuration map of the entire LAVA instance,
including the physical layout of the switches, all cables connected to all of
those switches and all the devices of that instance (not just test devices).
These constraints <strong>must all be met</strong> and can be summarized as:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#single-set-switches"><span class="std std-ref">Single set of switches</span></a></p></li>
<li><p><a class="reference internal" href="#vland-switch-support"><span class="std std-ref">Switches must have drivers in vland</span></a></p></li>
<li><p><a class="reference internal" href="#network-topology-map"><span class="std std-ref">Accurate map of network topology</span></a></p></li>
<li><p><a class="reference internal" href="#identify-primary-interfaces"><span class="std std-ref">Identification of primary interfaces</span></a></p></li>
<li><p><a class="reference internal" href="#vland-recommends"><span class="std std-ref">Additional advice</span></a></p></li>
</ul>
<section id="single-set-of-switches">
<span id="single-set-switches"></span><h3>Single set of switches<a class="headerlink" href="#single-set-of-switches" title="Permalink to this heading">¶</a></h3>
<p>All devices and all dispatchers must be on a single set of physical switches.
These virtual networks are <strong>local</strong>, no other topology is supported.</p>
</section>
<section id="switches-must-have-drivers-in-vland">
<span id="vland-switch-support"></span><h3>Switches must have drivers in vland<a class="headerlink" href="#switches-must-have-drivers-in-vland" title="Permalink to this heading">¶</a></h3>
<p>Switches which are expected to support a VLAN must have driver
support in <a class="reference external" href="https://gitlab.com/lava/vland">VLANd</a>.</p>
</section>
<section id="accurate-map-of-network-topology">
<span id="network-topology-map"></span><span id="index-1"></span><h3>Accurate map of network topology<a class="headerlink" href="#accurate-map-of-network-topology" title="Permalink to this heading">¶</a></h3>
<p>The physical topology of the LAN needs to be manually mapped and translated
into the <a class="reference internal" href="glossary.html#term-device-dictionary"><span class="xref std std-term">device dictionary</span></a> of the LAVA instance. This information must
be <strong>maintained and updated manually</strong> whenever the network topology is
changed.</p>
<p>The map must be complete and cover the identity of the switches and all the
port number(s) for all connections to those switches. It is <strong>strongly</strong>
recommended that administrators use the VLANd administration interface to
<strong>lock</strong> ports for devices that are not expected to be controlled in LAVA
tests, such as PDUs and the dispatcher itself. This will ensure that mistakes
in test configuration cannot alter connections to those devices which might
break the network.</p>
<p>The network map consists of:</p>
<ul>
<li><p>The <strong>identity of the switch and the port</strong> to which each interface of each
device under test is connected.</p></li>
<li><p>The <strong>MAC address and full sysfs path</strong> of the network interface of each
supported device. The <code class="docutils literal notranslate"><span class="pre">/sys/</span></code> path should <strong>not</strong> include the current
interface name (<code class="docutils literal notranslate"><span class="pre">eth0</span></code> etc.) as this can be changed with a different
userspace. e.g.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="o">/</span><span class="n">sys</span><span class="o">/</span><span class="n">devices</span><span class="o">/</span><span class="n">platform</span><span class="o">/</span><span class="n">ocp</span><span class="o">/</span><span class="mi">4</span><span class="n">a100000</span><span class="o">.</span><span class="n">ethernet</span><span class="o">/</span><span class="n">net</span><span class="o">/</span>
</pre></div>
</div>
</li>
<li><p>The list of unique <strong>interface names</strong>  for network interfaces on the device.
This <em>may</em> be something like eth0, eth1, etc., but the names used here will
<strong>not</strong> necessarily match up with the names that show up when the device is
actually running due to ordering issues when Linux boots. To remove any
possible confusion here, it is therefore recommended to <strong>not</strong> use the
eth0/eth1 names here.</p></li>
<li><p>The <strong>interface tags</strong> to describe each interface of each device. See
<a class="reference internal" href="vland.html#vland-device-tags"><span class="std std-ref">VLANd and interface tags in LAVA</span></a>. These tags will be useful information for test
writers to know, and will be used when selecting devices and interfaces to
match test definitions. Useful properties to list here may include things
like supported link speeds (100M, 1G, 10G etc.), device manufacturer (Intel,
Realtek, etc.), physical interface type (RJ45, SFP, etc.) - whatever test
writers are going to care about.</p></li>
</ul>
</section>
<section id="identify-primary-interfaces">
<span id="identification-of-primary-interfaces"></span><h3>Identification of primary interfaces<a class="headerlink" href="#identify-primary-interfaces" title="Permalink to this heading">¶</a></h3>
<p>Devices may have requirements that booting can only use certain interfaces
(which may be considered as <em>primary</em>), e.g. bootloaders may lack the ability
to detect and/or use a network interface which uses a USB network converter
when a physical ethernet port is also fitted. If the physical ethernet port is
put onto a VLAN, the bootloader may be unable to raise a network interface.
Test writers need to be able to know which interfaces should be typically be
avoided and lab admins can choose different methods for this support. See
<a class="reference internal" href="vland.html#vland-device-tags"><span class="std std-ref">VLANd and interface tags in LAVA</span></a>.</p>
<ul class="simple">
<li><p>Not specifying tags for <strong>primary</strong> interfaces or</p></li>
<li><p>Specifying only a <strong>special</strong> tag which test writers should normally avoid
using.</p></li>
</ul>
<p>The method chosen needs to fit with the <a class="reference internal" href="#network-topology-map"><span class="std std-ref">Accurate map of network topology</span></a> and the
particular use cases within each lab and LAN. See also
<a class="reference internal" href="vland.html#vland-multiple-interfaces"><span class="std std-ref">Requirement for multiple interfaces</span></a>.</p>
</section>
<section id="additional-advice">
<span id="vland-recommends"></span><h3>Additional advice<a class="headerlink" href="#additional-advice" title="Permalink to this heading">¶</a></h3>
<p>In addition, the following advice is strongly recommended:</p>
<ul class="simple">
<li><p>Admins should keep the device dictionary data in VCS and keep those copies
synchronized with the database.</p></li>
<li><p>Admins need to use the XML-RPC support to periodically <strong>verify</strong> that all
the devices have the correct configuration.</p></li>
<li><p>Admins need to ensure that any locked ports are re-established should there
be a power outage, maintenance window or other cause of switches being reset
or reconfigured.</p></li>
<li><p>Admins need to record the interfaces which may be considered <strong>primary</strong> for
each device. See <a class="reference internal" href="#identify-primary-interfaces"><span class="std std-ref">Identification of primary interfaces</span></a>.</p></li>
</ul>
<p>These items are an extension of the admin requirements for PDU ports and
connection commands and are to be considered in the same way. Any time that any
cables are moved around in the physical world, there will need to be a software
change, preferably in VCS and also in the database of the LAVA instance.</p>
</section>
</section>
<section id="example-device-dictionary">
<h2>Example device dictionary<a class="headerlink" href="#example-device-dictionary" title="Permalink to this heading">¶</a></h2>
<p>This example uses a non-existent <code class="docutils literal notranslate"><span class="pre">vland.yaml</span></code> template and imaginary sysfs
locations. Real datasets must extend a known template, typically the device
type template which itself extends the base template.</p>
<div class="highlight-jinja notranslate"><div class="highlight"><pre><span></span><span class="cp">{%</span> <span class="k">extends</span> <span class="s1">&#39;vland.yaml&#39;</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">set</span> <span class="nv">interfaces</span> <span class="o">=</span> <span class="o">[</span><span class="s1">&#39;iface0&#39;</span><span class="o">,</span> <span class="s1">&#39;iface1&#39;</span><span class="o">]</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">set</span> <span class="nv">sysfs</span> <span class="o">=</span> <span class="o">{</span>
<span class="s1">&#39;iface0&#39;</span><span class="o">:</span> <span class="s2">&quot;/sys/devices/pci0000:00/0000:00:19.0/net/&quot;</span><span class="o">,</span>
<span class="s1">&#39;iface1&#39;</span><span class="o">:</span> <span class="s2">&quot;/sys/devices/pci0000:00/0000:00:1c.1/0000:03:00.0/net/&quot;</span><span class="o">}</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">set</span> <span class="nv">mac_addr</span> <span class="o">=</span> <span class="o">{</span><span class="s1">&#39;iface0&#39;</span><span class="o">:</span> <span class="s2">&quot;f0:de:f1:46:8c:21&quot;</span><span class="o">,</span> <span class="s1">&#39;iface1&#39;</span><span class="o">:</span> <span class="s2">&quot;00:24:d7:9b:c0:8c&quot;</span><span class="o">}</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">set</span> <span class="nv">tags</span> <span class="o">=</span> <span class="o">{</span><span class="s1">&#39;iface0&#39;</span><span class="o">:</span> <span class="o">[</span><span class="s1">&#39;1G&#39;</span><span class="o">,</span> <span class="s1">&#39;10G&#39;</span><span class="o">],</span> <span class="s1">&#39;iface1&#39;</span><span class="o">:</span> <span class="o">[</span><span class="s1">&#39;1G&#39;</span><span class="o">]}</span> <span class="cp">%}</span>
<span class="cp">{%</span> <span class="k">set</span> <span class="nv">map</span> <span class="o">=</span> <span class="o">{</span><span class="s1">&#39;iface0&#39;</span><span class="o">:</span> <span class="o">{</span><span class="s1">&#39;switch2&#39;</span><span class="o">:</span> <span class="m">5</span><span class="o">},</span> <span class="s1">&#39;iface1&#39;</span><span class="o">:</span> <span class="o">{</span><span class="s1">&#39;switch1&#39;</span><span class="o">:</span> <span class="m">7</span><span class="o">}}</span> <span class="cp">%}</span>
</pre></div>
</div>
<p>This dictionary defines two interfaces belonging to the relevant device. It
uses python syntax to <strong>map</strong> each of those interfaces to values which need to
be extracted from the device itself:</p>
<ul class="simple">
<li><p><strong>sysfs</strong>: the full path in <code class="docutils literal notranslate"><span class="pre">/sys</span></code> to the device providing the interface.</p></li>
<li><p><strong>mac_addr</strong>: the MAC address of each interface - if the device is incapable
of retaining the same MAC address across power resets, the test writer will
need to use the <code class="docutils literal notranslate"><span class="pre">sysfs</span></code> information to work out which interface is which.</p></li>
<li><p><strong>tags</strong>: tags are used to select which devices of a particular <a class="reference internal" href="glossary.html#term-device-type"><span class="xref std std-term">device
type</span></a> can be assigned to the LAVA job. Although the link speed is the most
common value to be used, it could also be anything else which differs between
otherwise similar devices. See <a class="reference internal" href="vland.html#vland-device-tags"><span class="std std-ref">VLANd and interface tags in LAVA</span></a>. Tags are expressed
as a python dictionary of python lists.</p></li>
<li><p><strong>map</strong>: the switch and port map - the IP address or hostname of the switch
and the port on that switch from which there is a direct cable to the
physical port declared in the <code class="docutils literal notranslate"><span class="pre">sysfs</span></code> entry.</p></li>
</ul>
<section id="viewing-the-network-map">
<span id="vland-network-map"></span><h3>Viewing the network map<a class="headerlink" href="#viewing-the-network-map" title="Permalink to this heading">¶</a></h3>
<p>Device information can be viewed using <code class="docutils literal notranslate"><span class="pre">XML-RPC</span></code> using the
<code class="docutils literal notranslate"><span class="pre">system.pipeline_network_map</span></code> request. The function collates all the vland
information from pipeline devices to create a complete map, then return YAML
data for all switches or a specified switch.</p>
<div class="highlight-yaml notranslate"><div class="highlight"><pre><span></span><span class="nt">switches</span><span class="p">:</span>
<span class="w">  </span><span class="s">&#39;192.168.0.2&#39;</span><span class="p p-Indicator">:</span>
<span class="w">  </span><span class="p p-Indicator">-</span><span class="w"> </span><span class="nt">port</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">5</span>
<span class="w">    </span><span class="nt">device</span><span class="p">:</span>
<span class="w">      </span><span class="nt">interface</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">iface0</span>
<span class="w">      </span><span class="nt">sysfs</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;/sys/devices/pci0000:00/0000:00:19.0/net/&quot;</span>
<span class="w">      </span><span class="nt">mac</span><span class="p">:</span><span class="w"> </span><span class="s">&quot;f0:de:f1:46:8c:21&quot;</span>
<span class="w">      </span><span class="nt">hostname</span><span class="p">:</span><span class="w"> </span><span class="l l-Scalar l-Scalar-Plain">bbb1</span>
</pre></div>
</div>
</section>
</section>
</section>


    </div>
      
  </div>
</div>
<footer class="footer">
  <div class="container">
    <p class="pull-right">
      <a href="#">Back to top</a>
      
    </p>
    <p>
        &copy; Copyright 2010-2019, Linaro Limited.<br/>
      Created using <a href="http://sphinx-doc.org/">Sphinx</a> 5.3.0.<br/>
    </p>
  </div>
</footer>
  </body>
</html>